home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 July: Mac OS SDK / Dev.CD Jul 97 SDK1.toast / Development Kits (Disc 1) / PC Card Manager / CIncludes / IOIterator.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-01-13  |  4.3 KB  |  153 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        IOIterator.h
  3.  
  4.      Contains:    xxx put contents here xxx
  5.  
  6.      Version:    xxx put the technology version here xxx
  7.  
  8.      DRI:        Milton Soong
  9.  
  10.      Copyright:    © 1984-1996 by Apple Computer, Inc.
  11.                  All rights reserved.
  12.  
  13.      Warning:    *** APPLE INTERNAL USE ONLY ***
  14.                  This file may contain unreleased API's
  15.  
  16.      BuildInfo:    Built by:            SuperMario Build Daemon
  17.                  With Interfacer:    2.0d11   (PowerPC native)
  18.                  From:                IOIterator.i
  19.                      Revision:        3
  20.                      Dated:            3/5/96
  21.                      Last change by:    PK
  22.                      Last comment:    Change the parameter order in iteration API.
  23.  
  24.      Bugs:        Report bugs to Radar component “System Interfaces”, “Latest”
  25.                  List the version information (from above) in the Problem Description.
  26.  
  27. */
  28. #ifndef __IOITERATOR__
  29. #define __IOITERATOR__
  30.  
  31. #ifndef __TYPES__
  32. #include <Types.h>
  33. #endif
  34.  
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38.  
  39. #if PRAGMA_IMPORT_SUPPORTED
  40. #pragma import on
  41. #endif
  42.  
  43. #if PRAGMA_ALIGN_SUPPORTED
  44. #pragma options align=mac68k
  45. #endif
  46.  
  47. #if FOR_SYSTEM8_PREEMPTIVE
  48. /* typedefs*/
  49. typedef UInt32 IteratorDescVersion;
  50. /*
  51. ###########################################################
  52.  How to use the IteratorDescVersion
  53. ###########################################################
  54.  Each family will define a k<Family>CurrentIteratorDescVersion constant
  55.  in its *.i file. The client will check the returned IteratorDescVersion
  56.     value against this constant to make sure there's no version mismatch 
  57.      problem.
  58.  Common data structure used by all I/O family iterators
  59. */
  60. struct IODeviceRef {
  61.     UInt32                             contents[4];
  62. };
  63. typedef struct IODeviceRef IODeviceRef;
  64.  
  65. /*
  66.  a family unique reference number for returned devices.
  67.  this is an opaque field, for now, use the name registry Ref value of the             
  68.     device in question.    
  69.  The IODeviceRef is unique within a family, NOT unique across the entire I/O name space
  70. */
  71. struct IOCommonInfo {
  72.     IODeviceRef                     ref;
  73.     IteratorDescVersion             versionNumber;
  74. };
  75. typedef struct IOCommonInfo IOCommonInfo;
  76.  
  77. /* IteratorDescVersion versionNumber: version number of the family specific IOIteratorData*/
  78. #endif
  79. /*
  80. ###########################################################
  81.  How to copy name registry ref --> IODeviceRef
  82. ###########################################################
  83. {
  84.     IOCommonInfo            DeviceData;
  85.     RegEntryRef                *anotherReg, *whichDevice;
  86.     anotherReg = (RegEntryRef *)&DeviceData;
  87.     *anotherReg = *whichDevice;
  88. }
  89. ###########################################################
  90.  How to define a family specific IOIteratorData structure
  91. ###########################################################
  92.  struct <FamilyName>IOIteratorData
  93.  {
  94.       IOCommonInfo     IOCI;    
  95.                     // common data for all families    
  96.         f1,            // Individual family specific data
  97.         f2,
  98.         etc...
  99.  };
  100.  Example 1: (A possible implementation for the SCSI iterator)
  101.     struct SCSIIOIteratorData
  102.  {
  103.       IOCommonInfo     IOCI;    
  104.                     // common data for all families    
  105.         UInt32            BusID;
  106.         UInt32            TargetID;
  107.         UInt32            LUN;
  108.  };
  109. ###########################################################
  110.  How to define a family specific iterator function
  111. ###########################################################
  112. OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  113.             (    ItemCount             requestItemCount,
  114.                 FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),                              
  115.                 ItemCount             *totalItemCountPtr );
  116.                 
  117.  For returning ALL devices that the family have access to
  118.  OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  119.             (    UInt32                familySpecificParam,
  120.                 ItemCount             requestItemCount,
  121.                 FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),
  122.                 ItemCount             *totalItemCountPtr );
  123.                 
  124.  For returning a subset of devices, filtered by some family specific parameters
  125.  EXAMPLES:
  126.  OSStatus SCSIGetDeviceData 
  127.             (    ItemCount             requestItemCount,
  128.                 ItemCount             *totalItemCountPtr,
  129.                 SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  130.  To get all scsi devices
  131.  OSStatus SCSIBusGetDeviceData 
  132.             (    UInt32                BusID,
  133.                 ItemCount             requestItemCount,
  134.                 ItemCount             *totalItemCountPtr,
  135.                 SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  136.  To get all scsi devices that matches the input BusID
  137. */
  138.  
  139. #if PRAGMA_ALIGN_SUPPORTED
  140. #pragma options align=reset
  141. #endif
  142.  
  143. #if PRAGMA_IMPORT_SUPPORTED
  144. #pragma import off
  145. #endif
  146.  
  147. #ifdef __cplusplus
  148. }
  149. #endif
  150.  
  151. #endif /* __IOITERATOR__ */
  152.  
  153.